使用Swagger2Markup实现API文档的静态部署（一）：AsciiDoc
在阅读本文之前，您先需要了解Swagger的使用，如果您还不知道它是用来干嘛的，请先阅读《Spring Boot中使用Swagger2构建强大的RESTful API文档》一文。
前言
在学会了如何使用Swagger之后，我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。但是，如前文方式构建的文档必须通过在项目中整合 swagger-ui、或使用单独部署的 swagger-ui和 /v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
项目主页：https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前，我们先需要准备一个使用了Swagger的Web项目，可以是直接使用Swagger2的项目，也可以是使用了spring-boot-starter-swagger的项目，比如我仓库中的：https://github.com/dyc87112/swagger-starter-demo ，下面就来看看如何使用Swagger2Markup来创建AsciiDoc。
生成AsciiDoc
生成AsciiDoc的方式有两种：
通过Java代码来生成
第一步：编辑 pom.xml增加需要使用的相关依赖和仓库
<dependencies>...<dependency><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup</artifactId><version>1.3.1</version></dependency></dependencies><repositories><repository><snapshots><enabled>false</enabled></snapshots><id>jcenter-releases</id><name>jcenter</name><url>http://jcenter.bintray.com</url></repository></repositories>
第二步：编写一个单元测试用例来生成执行生成文档的代码
@RunWith(SpringRunner.class)@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)public class DemoApplicationTests {@Testpublic void generateAsciiDocs() throws Exception {// 输出Ascii格式Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC).build();Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")).withConfig(config).build().toFolder(Paths.get("src/docs/asciidoc/generated"));}}
以上代码内容很简单，大致说明几个关键内容：
MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUPfrom(newURL("http://localhost:8080/v2/api-docs")：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式toFolder(Paths.get("src/docs/asciidoc/generated")：指定最终生成文件的具体目录位置
在执行了上面的测试用例之后，我们就能在当前项目的src目录下获得如下内容：
src--docs----asciidoc------generated--------definitions.adoc--------overview.adoc--------paths.adoc--------security.adoc
可以看到，这种方式在运行之后就生成出了4个不同的静态文件。
输出到单个文件
如果不想分割结果文件，也可以通过替换 toFolder(Paths.get("src/docs/asciidoc/generated")为 toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。
通过Maven插件来生成
除了通过上面编写Java代码来生成的方式之外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，完全可以通过在 pom.xml中增加如下插件来完成静态内容的生成。
<plugin><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup-maven-plugin</artifactId><version>1.3.1</version><configuration><swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput><outputDir>src/docs/asciidoc/generated</outputDir><config><swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage></config></configuration></plugin>
生成HTML
好了，完成了从Swagger文档配置文件到AsciiDoc的源文件转换之后，就是如何将AsciiDoc转换成可部署的HTML内容了。这里继续在上面的工程基础上，引入一个Maven插件来完成。
<plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>1.5.6</version><configuration><sourceDirectory>src/docs/asciidoc/generated</sourceDirectory><outputDirectory>src/docs/asciidoc/html</outputDirectory><backend>html</backend><sourceHighlighter>coderay</sourceHighlighter><attributes><toc>left</toc></attributes></configuration></plugin>
通过上面的配置，执行该插件的asciidoctor:process-asciidoc命令之后，就能在 src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成之后，可以直接通过浏览器来看查看，你就能看到类似下图的静态部署结果：
是不是感觉似曾相识呢？是的，Spring Cloud的E版之前的文档也是这样的！！！
推荐阅读
微服务2017年度报告出炉：4大客户画像，15%传统企业已领跑
长按指纹
一键关注
点击 “阅读原文” 看看本号其他精彩内容